Windows Standard Serial Communications Library for C/C++ (WSC4C) USERS MANUAL Version 2.4 May 17, 1999 This software is provided as-is. There are no warranties, expressed or implied. Copyright (C) 1996-1999 All rights reserved MarshallSoft Computing, Inc. Post Office Box 4543 Huntsville AL 35815 Voice : 256-881-4630 FAX : 256-880-0925 email : info@marshallsoft.com web : www.marshallsoft.com _______ ____|__ | (R) --+ | +------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals --+--+ | +--------------------- |___|___| MEMBER WSC4C Users Manual Page 1 C O N T E N T S Chapter Page 1.0 Introduction................................................3 1.1 User Support............................................4 1.2 ASP Ombudsman...........................................4 1.3 Awards..................................................4 1.4 Installation............................................5 1.5 Uninstalling............................................5 1.6 Limitations on COM Ports................................5 2.0 Library Overview............................................6 2.1 Dynamic Link Libraries..................................6 2.2 Console Mode............................................6 2.3 Using the Library.......................................6 2.4 Static Libraries........................................7 2.5 Large Memory Model in Win16.............................7 2.6 Win32 STDCALL and DECLSPEC..............................7 2.7 Using Threads...........................................7 3.0 Compiling Programs..........................................8 3.1 Using a Makefile........................................8 3.2 Using an IDE............................................9 3.3 Compiling WSC..........................................11 3.4 Compiling Example Programs.............................11 4.0 Modem I/O..................................................12 4.1 MIO Introduction.......................................12 4.2 MIO Function Summary...................................12 5.0 XMODEM & YMODEM ...........................................13 5.1 XYDRIVER Introduction..................................13 5.2 XYDRIVER Function Summary..............................13 6.0 ASCII File Transfer........................................14 7.0 Problems...................................................15 8.0 Example Programs...........................................16 9.0 Legal Issues...............................................18 9.1 Registration...........................................18 9.2 Academic Discount......................................18 9.3 License................................................19 9.4 Warranty...............................................19 10.0 Summary....................................................20 10.1 Revision History......................................20 10.2 WSC Function Summary..................................21 10.3 Further Reading.......................................22 11.0 Other MarshallSoft Computing Products......................22 11.1 Personal Communications Library for C/C++.............22 11.2 Serial Libraries for Other Languages..................22 11.3 Internet Libraries....................................22 WSC4C Users Manual Page 2 1.0 Introduction The Windows Standard Serial Communications Library for C/C++ (WSC4C) is an asynchronous communications dynamic link library (DLL) which uses the standard Windows serial communications API. Since it uses the Windows API, programs using the WSC library are fully compatible with other Window applications which also use the Windows serial communications API. The WSC4C DLLs (WSC16.DLL and WSC32.DLL) can be called from any application capable of calling Windows API functions, including those written in C/C++, Delphi, Visual Basic, MS Access, MS Excel, Fortran, COBOL, PowerBuilder, FoxPro, Power Basic Console Compiler, dBase, etc. The library runs under NT, Windows 95/98, and Windows 3.1. Registered users can statically link WSC with their application rather than using the DLLs. Using WSC is very straight-forward. For example, to write "HELLO" to the serial port COM1: SioReset(COM1,512,512) /* open COM1 with 512 KB buffers */ SioPuts(COM1,"HELLO\r",6) /* write "HELLO" to COM1 */ SioDone(COM1) /* close COM1 */ Several C/C++ example programs with full source code are included. Refer to Chapter 8 for more details on each of the example programs. SIMPLE : A simple terminal emulator. SELFTEST : Performs COM port functionality testing. MODEM : Same as SIMPLE but controls flow control, modem lines, etc. TERM : Terminal emulator with XMODEM, YMODEM, and ANSI terminal emulator support. BCB : Borland C++ Builder (32-bit C++) example. MFC_PGM : Microsoft Foundation Class (MFC) example program. CONSOLE : A WIN32 console mode program similar to SIMPLE. FINDER : Finds a modem connected to one of your serial ports. ECHOPORT : Multi-threaded console mode program echoes all input. EVENT : Blocking version of SIMPLE. Uses SioEvent. XMS & XMR : Console mode XMODEM programs. RS485 : RS485 version of CONSOLE. WSC4C contains over 25 functions. All functions return a negative number if an error condition is detected. For more details, consult the WSC4C Reference Manual (WSC4C_R.TXT). Also see the RS232/485 Serial Communications Users Manual (ASYNC.TXT). Our goal is to provide a robust serial communications library that you and your customers can depend upon. Contact us if you have any questions. The shareware and registered versions are identical except that the shareware version displays the "shareware" screen when first starting, after 20 minutes of run time, and every 10 minutes after that. The registered version also includes source code. WSC4C Users Manual Page 3 1.1 User Support We want you to be successful in developing your applications using WSC4C! We depend upon our customers to let us know what they need in a communications library. If you have any suggestions or comments, please let us know. If you are having a problem using WSC4C, email us at support@marshallsoft.com You can also reach us at 256-881-4630 between 7:00 AM and 7:00 PM CST Monday through Friday. You can also often get us on the weekend. The latest versions of our products are available on our web site at http://www.marshallsoft.com and on our anonymous FTP site at ftp://ftp.marshallsoft.com/marshallsoft The MarshallSoft Computing newsletter "Comm Talk" is published quarterly on our web site. It discusses various communications problems and solutions using our products as well as related information. 1.2 ASP Ombudsman MarshallSoft Computing, Inc. is a member of the Association of Shareware Professionals (ASP). ASP wants to make sure that the shareware principle works for you. If you are unable to resolve a shareware-related problem with an ASP member by contacting the member directly, ASP may be able to help. The ASP Ombudsman can help you resolve a dispute or problem with an ASP member, but does not provide technical support for members' products. Please write to the ASP Ombudsman at 157-F Love Ave., Greenwood, IN 26142 USA, FAX 317-888-2195, or send email to omb@asp-shareware.org. 1.3 Awards WSC4C has been rated 4 stars by Ziff Davis on the web at http://www.hotfiles.com. The Visual Basic version (which uses the same DLLs) has been rated 5 stars, their highest rating. WSC4C is also one of the most popular downloads in the software tools section of many web download sites. WSC4C Users Manual Page 4 1.4 Installation Installation consists of copying WSC4C24.ZIP (WSC4C.ZIP for registered users) to a work directory, unzipping the files, running the INSTALL program, and compiling and running one of the example application programs such as SIMPLE. Unzip the files by typing PKUNZIP WSC4C24.ZIP Run the INSTALL batch file, which will copy the correct LIBs and DLLs for your compiler. INSTALL1 -- For all WIN16 Windows compilers (doesn't copy WIN32 DLL's). INSTALLU -- For WIN32 compilers supporting the "declspec" keyword, which includes MS Visual C/C++ 4.0 and above, Borland C/C++ 5.0 and above, Borland C++ Builder (all versions), and Watcom 11.0 and above. This is the preferred choice if possible. INSTALLM ++ Native Microsoft. INSTALLB ++ Native Borland. INSTALLW ++ Native Watcom. INSTALL.BAT also copies the proper DLL to your Windows directory, usually C:\WINDOWS or C:\WINNT. The WIN32 choices ("INSTALLU", etc) also copies WSC16.LIB and WSC16.DLL. WSC32.DLL & WSC32.LIB MIO32.DLL & MIO32.LIB XYDRV32.DLL & XYDRV32.LIB ASDRV32.DLL & ASDRV32.LIB You are now ready to compile and run a test program. Refer to Section 3.4 "Compiling Example Programs". 1.5 Uninstalling Uninstalling WSC4C is very easy. WSC4C does NOT modify the registry. First, delete the WSC4C project directory created when installing WSC4C. Second, delete WSC16.DLL and WSC32.DLL from your Windows directory, typically C:\WINDOWS for Windows 95/98 or C:\WINNT for Windows NT. Thats it! Running the UINSTALL.BAT batch file will also delete WSC16.DLL and WSC32.DLL as described above. 1.6 Limitations on COM Ports The 32-bit version of WSC4C (WSC32.DLL) can use any port from COM1 to COM20, provided that the port is known to Windows 95/98/NT and there is physical hardware present. More ports can easily be added by recompiling WSC32.C. WSC4C Users Manual Page 5 2.0 Library Overview 2.1 Dynamic Link Libraries WSC4C includes both Win16 [WSC16] and a Win32 [WSC32] dynamic link library (DLL). A DLL is characterized by the fact that it need not be loaded until required by an application program and that only one copy of the DLL is necessary regardless of the number of application programs that use it. Contrast this to the traditional static library which is bound to each and every application that uses it at link time. 2.2 Console Mode WSC4C functions can be called from WIN32 console mode programs. A "console mode" program is a Windows 95/98/NT WIN32 command line program running in a command window. Although console mode programs look like DOS programs, they are WIN32 programs which have access to the entire Windows address space. 2.3 Using the Library The WSC4C has been tested on multiple computers running Windows 3.1, Windows 95/98, and Windows NT 4.0. WSC4C has also been tested with Microsoft C/C++ 7.0 (from the Windows SDK), Microsoft Visual C/C++, Borland C/C++ (including C Builder), Turbo C/C++, and Watcom C/C++. Please examine the WSC.H file. Note that COM1 is defined as port zero, not port one. The user must assume the responsibility for passing the correct information when calling WSC4C functions. The INSTALL.BAT batch command file will copy the correct LIBs and DLLs. Refer to section 1.4 "Installation". WSC32U.DLL : For Microsoft Visual C/C++ 5.0, Borland C/C++ 5.0, Watcom C/C++ 11.0, and later compilers. WSC32B.DLL : Borland C/C++ 4.5 compilers. WSC32W.DLL : Watcom 10.5 and 10.6 compilers. 2.4 Static Libraries The registered user can easily compile WSC16.C (or WSC32.C) into his application, so that the WSC DLL's are not needed. The makefiles STATIC16._?_ and STATIC32._?_ compile WSC to create versions of SIMPLE which don't require the use of WSC16.DLL or WSC32.DLL. Static libraries require the source code for WSC, which is included in the registration package. WSC4C Users Manual Page 6 2.5 Large Memory Model in Win16 WSC16.DLL can be used from Win16 programs written in any memory model. Two examples are included in this archive for compiling SIMPLE.C for the large memory model. SIMPLE16._ML Large memory model makefile for Microsoft SIMPLE16._BL Large memory model makefile for Borland. 2.6 Win32 STDCALL and DECLSPEC WSC32 is compiled using the _stdcall and _declspec keywords. This means that WSC4C uses the same calling conventions and file naming conventions as the Win32 API. In particular, function names are NOT decorated. There is no leading underscore nor trailing "@size" added to function names. Microsoft Visual C/C++ users can look at the WSC32 function names using the dumpbin.exe executable: dumpbin /exports wsc32.dll Some older compilers do not support the "declspec" keyword. For this reason, we have provided two WSC.H prototype files: wsc32.h1 : For compilers NOT supporting "declspec". wsc32.h2 : For compilers which do support "declspec" (default). Versions of WSC for older compilers are also included. The proper versions are copied when running the INSTALL.BAT batch file. Refer to Section 1.4 "Installation" for more details. 2.7 Using Threads WSC4C is thread safe. Refer to the ECHOPORT example program, which demonstrates the use of multiple threads. ECHOPORT also demonstrates the use of the WIN32 Sleep() function. WSC4C Users Manual Page 7 3.0 Compiling Programs WSC4C has been tested using Microsoft, Borland, and Watcom C/C++ compilers. Before compiling, be sure that you have run INSTALL.BAT. The example programs can be compiled by using either the provided makefiles or creating a project file for the "Integrated Development Environments", or IDEs. Separate makefiles are provide for Win16 and Win32 programs. 3.1 Using a MAKEFILE Makefiles originated on UNIX systems. They are the standard way that C/C++ programs are constructed in command line environments. Windows programs can be constructed with makefiles from the DOS prompt using command line Windows compilers. Makefiles are provided for Microsoft, Borland, and Watcom command line compilers. Makefiles have file extensions of "_M_" and "MAK" for Microsoft, "_B_" for Borland, and "_W_" for WATCOM. Thus, SIMPLE16._W_ is the Watcom Win16 makefile for SIMPLE and SIMPLE32._M_ is the Microsoft Win32 makefile. Turbo C/C++ for Windows and Borland C++ Builder (BCB) do not support command line makefiles. The IDE must be used instead. The big advantage of makefiles over using an IDE is that all compiler switches and options can be completely specified within the makefile. A secondary advantage is that makefiles can be started from a batch file, completely automating the software build process. For this reason, makefiles are preferred over IDEs. WSC4C Users Manual Page 8 3.2 Using an IDE All windows compilers have an "Integrated Development Environment" (IDE) for building application programs in the Windows environment. Since there is no standard format for IDE project files, file names must be entered into the IDE from the keyboard. Each example program has a project text file (e.g. SIMPLE.PRJ) which contains the list of filenames that must be entered into the IDE. However, creating a project file within the IDE is very easy. Each application has a project file (SIMPLE.PRJ, TERM.PRJ, SELFTEST.PRJ, MODEM.PRJ). Each project file contains the filenames that must be entered into the IDE. For each IDE, you will have to enter these filenames into the IDE. This is usually done with the INS key except for the Microsoft Developer, which uses menu commands. Be careful to enter all filenames as listed in the ".PRJ" file. All of the example application programs have been built using IDE's from Microsoft, Borland, and Watcom. However, there are differences between IDE versions from the same compiler manufacturer. All of the IDEs use the concept of a file hierarchy. For example, the SIMPLE file hierarchy in the IDE should look like: SIMPLE.EXE +++ WSC16.LIB +++ ABOUT.C +++ LINE.C +++ PAINT.C +++ SIMPLE.C +++ SIOERROR.C +++ SIMPLE.DEF +++ SIMPLE.RC Replace WSC16.LIB above with WSC32.LIB for 32 bit applications. The order of the files is not significant. NOTE: Win32 Borland users must create the proper WSC32.LIB from WSC32.DLL by running the "implib" program in the compilers \BIN directory. implib wsc32.lib wsc32.dll Note the WSC32.LIB is also created in the Borland makefiles. 3.2.1 Microsoft IDE To create a new project, choose "Project", then "New". Select Win16 [Win32] as the target. A dialog box will then pop up into which the project file names are entered. WSC4C Users Manual Page 9 3.2.2 Microsoft Developer Studio To open an existing project, choose "File", then "Open Workspace", and then select "Makefiles" from the list of file types. See the MS Developer generated makefile SIMPLE.MAK. To create a new project, choose "File", then "New", then "Project Workspace". Select "Application" for "Type:" and a project name for "Name:". Choose Win16 or Win32 for platform. Then select "Create". Select "Insert", then "Files into Project". Add all filenames as listed in the ".PRJ" file corresponding to the project you are building. Lastly, select "Rebuild All". 3.2.3 Borland IDE To create a new project, first turn off LINKER case sensitivities: Choose "Options", "Projects", "Linker", "General". Turn off the "case sensitive link" and "case sensitive exports and imports" boxes. Next, choose "Project", then "New Project". Use the INS (Insert) key to pop up a dialog box into which the project file names are entered. Select "GUI" for the "Target Model:" Only "Runtime" and "Dynamic" should be checked for "Standard Libraries:" NOTE1: If, after linking in the IDE, you get unresolved external references to the communications library functions in which each function name is all upper case, then you have NOT turned off case sensitivity as described above. NOTE2: If you get errors compiling the windows header file "WINDOWS.H", turn on "Borland Extensions" in "Options", "Project", "Compiler", "Source". 3.2.4 Turbo C IDE Follow the same directions as above, except that the "Target Model:" can be any listed. 3.2.5 Borland C++ Builder To create a new project, Choose "File" / "Open Project" on the menu bar. Load BCB_PRJ.MAK. Then, choose "Build All" from "Project" to create the executable. 3.3.6 Watcom IDE To create a new project, choose "File", then "New Project". Enter the project name and then choose Win16 [Win32] as the target. Use the INS (Insert) key to pop up a dialog box into which the project file names are entered. Select "Options" from the main window, then "C Compiler Switches", then "10". Memory Models and Processor Switches". Check "80386 Stack based calling [-3s]", then check "32-bit Flat model [-mf]". WSC4C Users Manual Page 10 3.3 Compiling WSC WSC16.DLL and WSC32.DLL have been compiled using Microsoft Visual C/C++, and are callable from applications written using Microsoft, Borland, or Watcom compilers. If you recompile WSC32.C using Borland or Watcom compilers, then the resulting WSC32.DLL can only be used by applications compiled with the same compiler, unless the "_stdcall" and "_declspec" keywords are specified. Before compiling, be sure to run the installation batch file INSTALL.BAT, as explained in section 1.4 "Installation". For Microsoft C, type: NMAKE -f WSC16._M_ NMAKE -f WSC32._M_ For Borland C, type: MAKE -f WSC16._B_ MAKE -f WSC32._B_ For Watcom C, type: WMAKE -f WSC16._W_ WMAKE -f WSC32._W_ 3.4 Compiling Example Programs There are makefiles provided for each of the example programs. For example, to compile SIMPLE: For Microsoft C, type: NMAKE -f SIMPLE16._M_ NMAKE -f SIMPLE32._M_ For Borland C, type: MAKE -f SIMPLE16._B_ MAKE -f SIMPLE32._B_ For Watcom C, type: WMAKE -f SIMPLE16._W_ WMAKE -f SIMPLE32._W_ There is also a Microsoft Developer Studio generated makefile for SIMPLE. See SIMPLE.MAK. WSC4C Users Manual Page 11 4.0 MODEM I/O (MIO) 4.1 MIO Introduction The file MIO.H contains prototypes for using the Modem I/O DLL. These functions ease communicating with modems using AT commands. The TERM program contains an example of using the MIO functions. The Windows "operating system" is what is called "cooperative multitasking". The executing Windows task must voluntarily "give up" control before another Windows task (or Windows itself) can execute. The MIO functions are broken down into parts called states, and control is returned to Windows between executing each state. The MIO string buffer is set at 128 bytes. For example: (1) Send the string to the MIO driver by executing: Code = mioSendTo(Port,100,"!ATDT1,256,880,9748") The '!' characters are converted to carriage returns. The text string is copied into the driver's data area. (2) Call mioDriver (typically based on a timer) until MIO_IDLE is returned. Each time mioDriver is called, it will send another character to the modem provided the required delay (since the previous character was sent) has passed. If the delay has not passed, the driver simply returns MIO_RUNNING, but without actually sending a character to the modem. Once all characters have been sent, mioDriver will return MIO_IDLE, indicating it is done and is ready to accept another function. mioDriver will return MIO_RUNNING if it is still processing. Any other return value indicates that it is still processing and the returned value is a character from the modem that can be displayed if wanted. (3) Once mioDriver returns MIO_IDLE, call mioResult to get the result of the mioSendTo call. 4.2 MIO Function Summary mioDriver : Drives the execution of mioSendTo, mioWaitFor, or mioQuiet once they have been started. mioBreak : Forces the MIO driver to IDLE state. mioSendTo : Sends a string (including control chars) to the modem. mioWaitFor : Waits for a particular string from the modem, passing all else through. mioQuiet : Waits for continuous quiet of a specified duration. mioBreak : Breaks further modem I/O activity. Refer to the WSC Reference Manual for more information. WSC4C Users Manual Page 12 5.0 XMODEM & YMODEM 5.1 XYDRIVER Introduction The XMODEM & YMODEM functions are implemented in XYDRV as a DLL (Dynamic Link Library), and are state driven like the Modem I/O functions described in the previous section. The TERM program provides an example of using XYDRIVER. Also see the console mode example programs XMS and XMR. A timer is normally set up [ SetTimer(hMainWnd,1,125,NULL) ] which in turn calls xyDriver in the message loop in MainWndProc. WM_TIMER: Code = xyDriver(Port); ... break; Files can be sent and received using XMODEM, XMODEM/CRC, XMODEM/1K, and YMODEM. The basic procedure used to run XMODEM or YMODEM is as follows: (1) Call xyAcquire() immediately after calling SioReset(). (2) To receive a file, call xyStartRx(), then call xyDriver() repeatedly until XY_IDLE is returned. (3) To send a file, call xyStartTx(), then call xyDriver() repeatedly until XY_IDLE is returned. (4) Call xyRelease() immediately before calling SioDone(). Refer to the TERM program for examples of calling the XYDRV functions. 5.2 XYDRIVER Function Summary xyAbort : Abort driver at any time. xyAcquire : Acquire a port. xyDebug : Set the debug level. xyDriver : Executes the next state or states. xyGetMessage : Get the next debug message. xyGetParameter : Get a driver parameter. xyGetFileName : Get name of file being sent or received. xyRelease : Release a port. xyStartRx : Start a receive. xyStartTx : Start a transmit. Refer to the WSC Reference Manual for more information. WSC4C Users Manual Page 13 6.0 ASCII File Transfer 6.1 ASCII Protocol The "ASCII Protocol" is not a defined protocol, but rather it is a loose set of conventions developed over a period of years by BBS operators. Because XON/OFF flow control is used, only ASCII text can be transferred. The ASCII protocol is implemented as a DLL and is state driven like the MIO and XYDRVIVER code. (1) Call ascInit(Port,RxQueSize,xFlag) to do initialization, where Port = The connected port (COM1, COM2, etc). RxQueSize = The size of the Rx Queue as passed to SioReset(). xFlag = 1 if this module will perform XON/XOFF flow control. Set to FALSE if flow control is being performed by the WSC code (you called SioFlow()). (2) To send an ASCII file, call ascStartTx(FileName,CharPace,TermChar,EchoFlag), where FileName = The path & name of the file to send. CharPace = The delay in milliseconds between characters. TermChar = The termination character to send after the file has been sent. If none, use 0x00. EchoFlag = 1 if screen echo is desired. Then call ascDriver() until it returns IDLE (1). (3) To receive an ASCII file, call ascStartRx(FileName,TermChar,FirstWait,CharWait,EchoFlag), where FileName = The path & name of the file to send. TermChar = The termination character. If none, use 0x00. FirstWait = The maximum number of seconds to wait for the first incoming character. CharWait = The maximum number of seconds after which it is assumed that the other side has completed sending. If unsure, set this to 3 seconds. EchoFlag = 1 if screen echo is desired. Then call ascDriver() until it returns IDLE (1). 6.2 ASCII Function Summary ascAbort : Abort driver at any time. ascDriver : Executes the next state or states. ascGetMessage : Get the next debug message. ascGetParameter : Get a driver parameter. ascGetFileName : Get name of file being sent or received. ascInit : Initialize the driver. ascStartRx : Start a receive. ascStartTx : Start a transmit. WSC4C Users Manual Page 14 7.0 Problems If you cannot get your application to run properly, first compile and run the terminal emulator program SIMPLE provided on your distribution disk. Test SIMPLE by connecting two computers with a null modem cable or by commanding a Hayes AT command set compatible modem. Once SIMPLE runs, compile and run the SELFTEST program. This program will test your serial ports' functionality. If your application does not run but SIMPLE and SELFTEST run correctly, then you have most likely made a programming mistake in your application. MarshallSoft Computing cannot debug your application, especially over the telephone! However, consider each of the following when searching for an error in your application. 1. Have you included the file WSC.H in your application? If WSC.H does not exist, then you have not run INSTALL.BAT. 2. Are your receive and transmit buffers large enough? Use a buffer size that is twice the size of the largest expected block. 3. Have you selected too high a baud rate? Windows can multitask many tasks at once. You may have to lower your baud rate (or get 16550 UARTS). 4. Did SioReset return a zero value? If not, then you must call SioReset again. 5. Did you send the proper initialization string to your modem? Did you set DTR and RTS? (you should). 7. Are you trying to link a 32-bit DLL to a 16-bit program (or vice versa)? Keep Win16 & Win32 development separate. 8. If you are using the registered version of WSC and you are still getting the shareware screen, make sure you have deleted all copies of the WSC shareware DLL's in the Windows search path. 9. If you do not have the WSC.H file, you have not run INSTALL.BAT. We recommend the following steps if you believe that you have discovered a bug in the library: (1) Create the smallest, simplest test program possible that demonstrates the problem. (2) Document your exact machine configuration and what error the test program demonstrates. (3) Email us the example source. If the problem can be solved with an easy work-around, we will publish the work-around. If the problem requires a modification to the library, we will make the change and make the modified library available to our customers without charge. WSC4C Users Manual Page 15 8.0 Example Programs 8.1 SIMPLE SIMPLE is a very simple communications program using WSC4C. Everything typed on the keyboard is sent to the serial port, and everything incoming from the serial port is displayed on the screen. The easiest way to test SIMPLE is to connect to a modem. Typing "AT" should result in an "OK" being displayed. 8.2 SELFTEST SELFTEST performs a serial port I/O functionality test using a loopback adapter. Refer to LOOPBACK.TXT for an explanation of how to make a loopback adapter (without tools!). 8.3 MODEM MODEM is similar to SELFTEST, but with enhanced capability. It can set flow control (hardware, software, or none), DTR line (set or clear), RTS line (set or clear), display the transmit & receive queue sizes, detect a break signal, detect changes in DSR and CTS, as well as check for various line errors (parity error, framing error, data overrun, receive queue overflow, and transmit buffer full). 8.4 TERM TERM is a simple ANSI terminal emulator suitable for calling up a BBS and downloading or uploading files using XMODEM or YMODEM. The TERM program uses MIO16.DLL (or MIO32.DLL) for modem control commands, and XYDRV16.DLL (or XYDRV32.DLL) for XMODEM & YMODEM file transfer. Selecting "Dial" from the menu bar will result in a pop-up dialog requesting the phone number to dial. Once entered, the number is dialed, and the program will wait for up to 60 seconds for the "CONNECT" string from the modem. This wait can be terminated at any time by choosing "BREAK" on the menu bar. Once logged on, files can be uploaded or downloaded by selecting "Send" or "Receive" from the menu bar. To abort a file transfer, choose "BREAK" from the menu bar then type a series of Ctrl-X (^X) characters from the keyboard. TERM uses ANSI.C, which provides ANSI terminal emulator support. WSC4C Users Manual Page 16 8.5 BCB_PGM BCB_PGM is a Borland C++ Builder example program similar to SIMPLE. BCB_PRJ.MAK is the makefile necessary for building BCB_PGM.EXE. 8.6 MFC_PGM MFC_PGM is a Microsoft Foundation Class C++ program similar to SIMPLE. MFCPGM16.MAK is the Win16 makefile and MFCPGN32.MAK is the Win32 makefile. 8.7 CONSOLE The CONSOLE program is a WIN32 console mode program similar to SIMPLE. It also demonstrates how to acquire and manipulate the standard input handle so that a "KeyPress" function can be implemented. CONSOLE takes the port and baud rate as arguments. For example, to start CONSOLE on COM1 at 38,400 baud: CONSOLE 1 38400 8.8 FINDER The FINDER program is a WIN32 console mode program that searches for a connected modem. Your modem must be connected to one of COM1 through COM4, and the modem must be turned on. FINDER takes no arguments. 8.9 ECHOPORT The ECHOPORT console mode program demonstrates the use of threads. Connect COM1 and/or COM2 to another computer or serial device using a NULL modem cable. ECHOPORT will echo back to the remote anything it receives on the serial port. ECHOPORT takes no arguments. 8.10 EVENT The EVENT console mode program demonstrates the use of SioEvent in efficiently waiting for serial input. No polling or timer is required. EVENT operates like SIMPLE. 8.11 XMS and XMR XMS (XMODEM Send) and XMR (XMODEM Receive) are console mode programs that send and receive files using the XMODEM protocol. 8.12 RS485 The RS485 example program operates like SIMPLE, except that it assumes an RS485 port. RTS is set before transmitting data, and cleared after the last bit of the last byte has been sent. WSC4C Users Manual Page 17 9.0 Legal Issues 9.1 Registration WSC4C may be registered for $85 plus $7 S&H ($12 outside of North America). To order, contact us as shown on the title page of this manual. All prices are guaranteed for one year from the release date. Multiple copy discounts (3 or more) and site licenses are available. Please call for details. We accept American Express, VISA, MasterCard, Discover, checks in US dollars drawn on a US bank, International Postal Money Orders, purchase orders (POs) from recognized US schools and companies listed in Dun & Bradstreet, and COD (street address and phone number required) within the USA (plus a $5 COD charge). For credit card orders, be sure to include the account number, the expiration date, the exact name on the card, and the complete card billing address (address to which the credit card bill is mailed). Credit card orders can be called in, emailed, faxed or submitted using our secure server at www.marshallsoft.com. Print the file INVOICE.TXT if a "Pro Forma" invoice is needed. Note that all ordering information collected, including email addresses, is kept strictly confidential. If you wish to update from an older version of WSC4C, send $30 plus $7 S&H ($12 S&H outside of North America). The registered package includes: o Win16 & Win32 WSC4C Libraries w/o shareware screens. o Win16 & Win32 source code for WSC, MIO, and XYDRIVER. o Printed Users Manual & Reference Manual. o Telephone and email support for one year. The registered user will receive the latest version of WSC4C shipped by US second day priority mail (packet airmail overseas). A 3.5" HD diskette is provided. 9.2 Academic Discount We offer an "academic price" of 40% off the normal price for prepaid email orders to faculty and students currently enrolled in any accredited high school, college, or university. To qualify for the discount, your school must have a web site and you must have an email address at your school. When ordering, ask for the "academic discount", or enter "student at" (or "faculty at") and your schools web site address (URL) in the comments field of the order form on our web site order page . Your order will be sent to your email address at your school. This offer is not retroactive and cannot be used with any other discount. Products bought with academic pricing can not be used for any commercial purpose. WSC4C Users Manual Page 18 9.3 License MarshallSoft Computing, Inc. grants the registered user of WSC4C the right to use one copy of the WSC4C library (in object form) on a single computer in the development of any software product (other than libraries such as WSC4C). The user may not use the library on more than one computer at the same time. The source code for the library (WSC16.C, WSC32.C, MIO.C, and XYDRV.C) is copyrighted by MarshallSoft Computing and may not be released in whole or in part. The registered DLLs may be distributed (without royalty) in object form only, as part of the user's application, provided that the application is NOT a compiler, interpreter, or other software development program. 9.4 Warranty MARSHALLSOFT COMPUTING, INC. DISCLAIMS ALL WARRANTIES RELATING TO THIS SOFTWARE, WHETHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY AND SPECIFICALLY DISCLAIMED. NEITHER MARSHALLSOFT COMPUTING, INC. NOR ANYONE ELSE WHO HAS BEEN INVOLVED IN THE CREATION, PRODUCTION, OR DELIVERY OF THIS SOFTWARE SHALL BE LIABLE FOR ANY INDIRECT, CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE SUCH SOFTWARE EVEN IF MARSHALLSOFT COMPUTING, INC. HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR CLAIMS. IN NO EVENT SHALL MARSHALLSOFT COMPUTING, INC.'S LIABILITY FOR ANY SUCH DAMAGES EVER EXCEED THE PRICE PAID FOR THE LICENSE TO USE THE SOFTWARE, REGARDLESS OF THE FORM OF THE CLAIM. THE PERSON USING THE SOFTWARE BEARS ALL RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE. Some states do not allow the exclusion of the limit of liability for consequential or incidental damages, so the above limitation may not apply to you. This agreement shall be governed by the laws of the State of Alabama and shall inure to the benefit of MarshallSoft Computing, Inc. and any successors, administrators, heirs and assigns. Any action or proceeding brought by either party against the other arising out of or related to this agreement shall be brought only in a STATE or FEDERAL COURT of competent jurisdiction located in Madison County, Alabama. The parties hereby consent to in personam jurisdiction of said courts. WSC4C Users Manual Page 19 10.0 Summary 10.1 Revision History Version 1.0: September 6, 1996. o The initial release of WSC4C. Version 2.0: January 25, 1997. o Includes Win32 libraries [Microsoft, Borland, Watcom]. o Added XMODEM & YMODEM DLL (XYDRIVER.DLL). o Added TERM example program. Version 2.1: June 2, 1997. o Added ANSI terminal emulator support. o Added "expires" option to SioInfo(). [SHAREWARE ONLY]. o Added SioRead function. o Added Borland C Builder example program. Version 2.2: October 1, 1997. o Fixed problem in XYDRV.C (renamed from XYDRIVER.C) o Added xyGetFileName function to XYDRV. o WSC4C supports up to 16 ports. o WSC4C runs under Windows NT. o Added Microsoft Foundation Class (MFC) Example. o Added ASCII protocol. Version 2.3: July 15, 1998. o Multiple changes to XYDRV for added capability. o SioTimer() function added to WSC16 and WSC32. o FINDER example modem search program added. o CONSOLE example console mode program added. o ECHOPORT example multi-thread program added. o SioBaud & SioParms can be called before SioReset. o WSC32.C modified so that the number of supported ports can be easily increased. Version 2.4: May 17, 1999. o SioEvent function added (WIN32 only). o New xyDriver code. o New XMODEM example programs (XMS and XMR). o New RS485 example program. o Specify default DTR & RTS behavior with SioReset. WSC4C Users Manual Page 20 10.2 WSC Function Summary Refer to the WSC4C Reference Manual (WSC4C_R.TXT) for detailed information on the communications and support functions. Refer to the RS232/485 Serial Communications Users Manual (ASYNC.TXT) for technical information on UARTs, modems, and other RS232 issues. A one line summary of each function follows: +-------------+-----------------------------------------------------+ | SioBaud | Sets the baud rate of the selected port. | | SioBrkSig | Asserts, cancels, or detects BREAK signal. | | SioCTS | Reads the Clear to Send (CTS) modem status bit. | | SioDCD | Reads the Data Carrier Detect (DCD) modem status. | | SioDone | Terminates further serial processing. | | SioDSR | Reads the Data Set Ready (DSR) modem status bit. | | SioDTR | Set, clear, or read the Data Terminal Ready (DTR). | | SioEvent | Wait for specified event. | | SioFlow | Enables / disables hardware flow control. | | SioGetc | Reads the next character from the serial line. | | SioGets | Receives a string of characters. | | SioInfo | Returns information such as library version. | | SioParms | Sets parity, stop bits, and word length. | | SioPutc | Transmit a character over a serial line. | | SioPuts | Transmits a string of characters. | | SioRead | Reads any UART register. | | SioReset | Initialize a serial port for processing. | | SioRI | Reads the Ring Indicator (RI) modem status bit. | | SioRTS | Sets, clears, or reads the Request to Send (RTS). | | SioRxClear | Clears the receive buffer. | | SioRxQue | Returns the number of characters in the RX queue. | | SioStatus | Returns the serial port line status. | | SioTimer | Returns the system times in milliseconds. | | SioTxClear | Clears the transmit buffer. | | SioTxQue | Returns the number of characters in the TX queue. | | SioUnGetc | "Ungets" (puts back) a specified character. | | SioWinError | Returns Win32 error message as text. | +-------------+-----------------------------------------------------+ WSC4C Users Manual Page 21 10.3 Further Reading The best way to learn about serial communications is to read a good book on the subject. Several good texts are available. Two that I like are: (1) C Programmer's Guide to Serial Communications by Joe Campbell (SAMS) (2) Mastering Serial Communications by Peter Gofton (SYBEX). 11.0 Other MarshallSoft Computing Products Several shareware products are available from MarshallSoft Computing. 11.1 The Personal Communications Library for C/C++ The Personal Communications Library for C/C++" (PCL4C) is a DOS based serial communications library supporting real and protected mode DOS. PCL4C supports ports COM1 through COM20 to 115200, 4+ ports concurrently, many dumb multiport boards, 16550, 16650, and 16750 UARTs. PCL4C is interrupt driven, supporting RTS/CTS flow control, any UART address and IRQ, all memory models. PCL4C can be used with Watcom C/C++, Borland/Turbo C/C++, MIX Power C, and Microsoft C/C++. 11.2 Serial Libraries for Other Languages We have DOS and Windows communications libraries for C/C++, Turbo Pascal, Visual Basic, and PowerBASIC. All PCL libraries support the 8250, 16450, 16550, 16650, and 16750 UARTs. Check our WEB site. PCL4C : C/C++, DOS (includes 16-bit protected mode). PCL4P : Turbo Pascal, DOS (includes 16-bit protected mode). PCL4VB : Visual Basic, DOS (VBDOS). Also supports Quick Basic. PCL4PB : PowerBASIC, DOS. WSC4C : C/C++, Win 3.1/95/98/NT. Uses Windows API. WSC4VB : Visual Basic, Win 3.1/95/98/NT. Uses Windows API. WSC4D : Borland Delphi, Win 3.1/95/98/NT. Uses Windows API. WSC4PB : PowerBASIIC Console Compiler, Win 95/98/NT. Uses Win API. 11.3 Internet Libraries WIL4C : C/C++, Win 3.1/95/98/NT. The "Winsock Interface Library" supports TCP,SMTP,POP3,TELNET,FTP, etc. SEE4C : C/C++, Win 3.1/95/98/NT. Email from your C/C++ application using the "SMTP/POP3 Email Engine for C/C++" (SEE4C), including MIME attachments. Also versions for Delphi (SEE4D), Visual Basic (SEE4VB), PowerBASIC (SEE4PB), COBOL (SEE4CB), Fortran (SEE4F), and Visual dBase (SEE4DB). FCE4C : C/C++, Win 3.1/95/98/NT. Upload & download files using FTP. WSC4C Users Manual Page 22